This PR prototypes the safety documentation part of the unsafe-v2 migration tooling (tracking issue §5), continuing #131002, #131245 and #131454. Everything here is non-shipping (#if DEBUG) and disabled by default.

Background

Passing an obligation to a caller comes with a responsibility to say what that obligation is, and discharging one comes with a responsibility to say how. IL5005 from #131002 covers the first half: an unsafe member must carry a <safety> XML comment. Two gaps remain.

The first is the other side of the same contract. An unsafe region is where the obligations are actually met, and that reasoning is invisible unless it is written down. The speclet recommends Rust-style // SAFETY comments and LDM 2026-05-27 left "compiler or analyzer?" open, so an analyzer is the natural home.

The second is safe itself. It is a hand-written assertion the compiler cannot verify, and it is arguably the annotation that most needs a recorded audit, yet nothing checks it.

Changes in this PR

1. 🔍 UnsafeBlockMissingSafetyCommentAnalyzer (IL5009) reports an unsafe block or unsafe(...) expression with no // SAFETY: comment. A region nested inside an already-documented one is not reported, since the outer comment covers it.

2. 🔧 AddSafetyCommentCodeFixProvider fixes IL5009 by inserting a // SAFETY: TODO stub, matching the /* SAFETY: Audit */ convention Add unsafe modifier migration code fixer #131002 already uses. The stub only marks the region for review; describing the reasoning is the developer's job.

3. 🔍 SafeModifierMissingJustificationAnalyzer (IL5010) reports an explicit safe modifier with no <safety> documentation, wherever safe can appear: extern members and [LibraryImport] methods, where it claims the native boundary upholds its contract, and fields in explicit or extended layouts, where it claims the overlap cannot be used to type-pun. No code fix, since only a developer can write the justification.

The SAFETY: marker

Recognized by \bSAFETY\s*:, case-sensitive, matched anywhere inside a comment.

Accepted: // SAFETY:, //SAFETY:, // Reads one element. SAFETY: ..., /* SAFETY: ... */, and a marker on an inner line of a block comment. Rejected: // UNSAFETY: and // SAFETYNET: (whole word), // SAFETY concerns are handled elsewhere (no colon), and // safety: or // Safety:.

Case sensitivity is deliberate: it keeps git grep 'SAFETY:' authoritative as an audit tool, at the cost of a mildly confusing report for someone who writes // Safety:. Both that and the leniency about spacing before the colon are pinned by tests, so they are easy to revisit.

Notable case handled

unsafe(...) expressions are newer than the Roslyn these analyzers compile against, so UnsafeExpressionSyntax and SyntaxKind.UnsafeExpression are unavailable at build time even though they exist at run time. Detecting the expression form as "an unsafe keyword followed by (" is wrong: the modifier is also followed by ( on any member whose type is a tuple.

public static unsafe (int, int) GetPair() => default;   // modifier, not a region
int x = unsafe(Read());                                 // the actual expression

That shape is pervasive in the hardware intrinsics (AdvSimd.cs alone has around 15), and every one of them would have been reported as an undocumented unsafe region, with the fixer offering to stamp a // SAFETY: TODO on it. The analyzer instead tests token.Parent is ExpressionSyntax, which is version-safe because ExpressionSyntax predates the feature.

Diagnostics IDs

Just for reference

• IL5005 [Add unsafe modifier migration code fixer #131002] - An unsafe member has no <safety> XML documentation.
• IL5009 [This PR] - An unsafe region has no // SAFETY: comment.
• IL5010 [This PR] - An explicit safe modifier has no justification.

Known limitations / follow ups

• IL5009 treats any // SAFETY: comment as sufficient. It cannot judge whether the reasoning is correct, or whether it still applies after the region is edited.
• The nesting exemption is deliberately coarse: a documented outer region silences every region inside it, even a much later one that may warrant its own note.
• This branch adds UnsafeMigrationSyntaxHelpers.SafeKeywordKind, which Add unsafe contract consistency code fixes #131454 also adds. Whichever merges second will need a trivial conflict resolution.

Testing

ILLink.RoslynAnalyzer.Tests: 1238 passed. New coverage for both region forms, the accepted and rejected marker spellings, nesting in both directions, unsafe expressions in field initializers where a block is not valid syntax, the tuple-returning modifier shapes above, and safe on both extern members and explicit-layout fields.